d/[..]/grub.d/xen.cfg: command line "starter kit"

As pointed out by Gergely in debian bug #919758, the examples in the
grub documentation contain incorrect suggestions, at least for dom0_mem
and earlyprintk.

Correct those, and take the opportunity to refresh all of this a bit,
including the most common set of used options.

Also, point to the online documentation where more explanation about all
options can be found.

(Closes: #919758)

diff --git a/debian/changelog b/debian/changelog
index 85ec16a93eaa6aa3c9060edddfd773a9530f08a0..1f9f6cd4398aa665392d6db7d2301ce1ff792b97 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,8 +1,9 @@
 xen (4.11.1-2~) UNRELEASED; urgency=medium
 
-  * 
+  * Refresh hypervisor and dom0 command line options documentation.
+    (Closes: #919758)
 
- -- Ian Jackson <ijackson@chiark.greenend.org.uk>  Thu, 10 Jan 2019 15:45:18 +0000
+ -- Hans van Kranenburg <hans@knorrie.org>  Sun, 20 Jan 2019 00:46:00 +0100
 
 xen (4.11.1-1) unstable; urgency=medium
 

diff --git a/debian/tree/xen-hypervisor-common/etc/default/grub.d/xen.cfg b/debian/tree/xen-hypervisor-common/etc/default/grub.d/xen.cfg
index c16e65706728098379c62c00c2fd57212e40c3a6..feb4be78e968f737d1bd1f18b5e87bea0efe1a66 100644 (file)
--- a/debian/tree/xen-hypervisor-common/etc/default/grub.d/xen.cfg
+++ b/debian/tree/xen-hypervisor-common/etc/default/grub.d/xen.cfg
@@ -15,16 +15,37 @@ echo "Including Xen overrides from /etc/default/grub.d/xen.cfg"
 #GRUB_CMDLINE_XEN_DEFAULT=""
 #GRUB_CMDLINE_XEN=""
 #
-# For example:
+# Commonly used options are:
+#
+# dom0_mem=<size>
+#   Sets the amount of memory dom0 uses to a fixed size. All other memory
+#   will be usable for domUs. For x86, this prevents ballooning actions
+#   from happening to take away memory from the dom0 or return it back. For
+#   arm, setting this option is required. E.g. dom0_mem=4G
+#
+# dom0_max_vcpus=<min>-<max>
+#   Limits the amount of physical cpus that dom0 is using, so it will not
+#   try to be scheduled on all available cpus all the time. Xen will try to
+#   provide the maximum value of vcpus, but will also gracefully deal with
+#   a situation of hotplugging physical cpus and reduce the number of vcpus
+#   instead of oversubscribing the system.  E.g. dom0_max_vcpus=1-4
 #
-# dom0_mem=<size>[M]:max=<size>[M]
-#   Sets the amount of memory dom0 uses (max prevents balloning for more)
 # com[12]=<speed>,<data bits><parity><stopbits>
-#   Initialize a serial console from in the hypervisor (eg. 115200,8n1)
-#   Note that com1 would be ttyS0 in Linux.
+#   Initialize a serial console for the hypervisor. Note that com1 would be
+#   ttyS0 in Linux when running without Xen. E.g. com1=115200,8n1
+#
 # console=<dev>[,<dev> ...]
-#   Redirects Xen hypervisor console (eg. com1,vga)
-
+#   Specify which console(s) Xen should use. E.g. console=com1,vga
+#
+# xpti=dom0=<bool>,domu=<bool> (only for x86)
+#   Override default selection of whether to isolate 64-bit PV guest page
+#   tables. If the dom0 is only used for managing domUs, and no untrusted
+#   code is ran inside, xpti for dom0 can be turned off for performance
+#   reasons. E.g. xpti=dom0=false,domu=true
+#
+# Please also refer to the "Xen Hypervisor Command Line Options"
+# documentation for the version of Xen you have installed. This
+# documentation can be found at https://xenbits.xen.org/
 #
 # The next two lines are used for creating kernel arguments for the dom0
 # kernel. This allows to have different options for the same kernel used
@@ -35,10 +56,14 @@ echo "Including Xen overrides from /etc/default/grub.d/xen.cfg"
 #
 # For example:
 #
-# earlyprintk=xenboot
+# earlyprintk=xen
 #   Allows to send early printk messages to the Xen hypervisor console
+#
 # console=hvc0
-#   Redirects the Linux console to the hypervisor console
+#   Redirects the Linux console to the hypervisor console. When running
+#   under Xen as dom0, this needs to be specified, because the usual ttyS0
+#   will not be available. When viewing the serial console, pressing Ctrl-A
+#   three times will switch between the Linux dom0 and the Xen Hypervisor.
 
 #
 # Make booting into Xen the default if not changed above. Finding the